---
id: api
title: BaseTable API
---

## 组件 props

:::info
dataSource 和 columns 是必传 props，其他 props 均可选。
:::

### 主要字段

| 字段             | 类型                                                    |                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`dataSource`** | `any[]`                                                 | 表格数据源                                                                                                                                                              |
| **`columns`**    | `ArtColumn[]`                                           | 表格的列配置                                                                                                                                                            |
| `isLoading`      | `boolean`                                               | 表格是否在加载中                                                                                                                                                        |
| `primaryKey`     | `string` <br/> 或 `(row: any) => string`                | 用于指定每一行的 key<br/>传入字符串表示从数据中获取对应字段的值作为 key<br/>传入函数时将调用该函数来生成每一行的 key<br/>不传该 prop 时，表格将使用下标作为每一行的 key |
| `getRowProps`    | `(record: any, rowIndex: number): React.HTMLAttributes` | 自定义每一行的 props                                                                                                                                                    |

### 其他字段

| 字段                 | 类型                                                      |                                                                                    |
| -------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `className`          | `number`                                                  | 自定义类名                                                                         |
| `style`              | `React.CSSProperties`                                     | 自定义内联样式                                                                     |
| `hasHeader`          | `boolean`                                                 | 表格是否具有头部                                                                   |
| ~~`isStickyHead`~~   | `boolean`                                                 | 请使用 `isStickyHeader` 代替                                                       |
| `isStickyHeader`     | `boolean`                                                 | 表格头部是否吸顶，默认为 true                                                      |
| `stickyTop`          | `number`                                                  | 表头吸顶后，距离顶部的距离，默认为 0                                               |
| `useOuterBorder`     | `boolean`                                                 | 是否使用来自外层 div 的边框代替单元格的外边框，默认为 false                        |
| `defaultColumnWidth` | `number`                                                  | 列的默认宽度                                                                       |
| `emptyCellHeight`    | `number`                                                  | 数据为空时，单元格的高度                                                           |
| `footerDataSource`   | `any[]`                                                   | 表格页脚数据源（数据中的字段一般要与 `dataSource` 相同）                           |
| `isStickyFooter`     | `boolean`                                                 | 表格页脚是否吸附在表格底部，默认为 true                                            |
| `hasStickyScroll`    | `boolean`                                                 | 表格是否包含自定义的横向粘性滚动条是否出现，默认为 true                            |
| `stickyScrollHeight` | `'auto' / number`                                         | 指定自定义横向滚动条的高度，在定制滚动条样式时有用，默认为 `'auto'`                |
| `stickyBottom`       | `number`                                                  | 表格底部距离页面下边缘的距离                                                       |
| `useVirtual`         | `'auto'` <br/> 或 `boolean` <br/> 或一个对象              | 是否开启虚拟滚动，用法详见[进阶用法-虚拟滚动](/docs/table/advanced-usage#虚拟滚动) |
| `flowRoot` \*        | ~~`'auto' / 'self' / HTMLElement / (() => HTMLElement)`~~ | ~~表格所处于的块格式化上下文(BFC)~~ <br/> v2.4 该属性已被移除                      |
| `estimatedRowHeight` | `number`                                                  | 虚拟滚动开启情况下，表格中每一行的预估高度                                         |
| `components`         | `object`                                                  | 自定义表格内部使用的子组件，详见下方                                               |

- flowRoot \* (v2.4 该属性已被移除) ~~[块格式化上下文](https://developer.mozilla.org/zh-CN/docs/Web/Guide/CSS/Block_formatting_context) 用于在开启虚拟滚动的情况下计算表格的可见范围。~~

### 自定义表格内的子组件

| 字段                               | 类型                  |                                                          |
| ---------------------------------- | --------------------- | -------------------------------------------------------- |
| ~~`props.emptyContent`~~           | ~~`React.ReactNode`~~ | ~~请使用 `components.EmptyContent` 代替~~                |
| `components.LoadingIcon`           | `React.ComponentType` | 自定义加载图标                                           |
| `components.EmptyContent`          | `React.ComponentType` | 自定义数据为空时表格的展示内容                           |
| `components.LoadingContentWrapper` | `React.ComponentType` | 自定义表格内容的 wrapper div，可用于实现自定义的加载效果 |
| `components.TableBody`             | `React.ComponentType` | 自定义 tbody 元素的渲染                                  |
| `components.Row`                   | `React.ComponentType` | 自定义 tr 元素的渲染                                     |
| `components.Cell`                  | `React.ComponentType` | 自定义 td 元素的渲染                                     |

`components.*` 的默认值如下，覆盖时可供参考：

```tsx
function LoadingContentWrapper({ children, visible }: LoadingContentWrapperProps) {
  // visible 表示表格是否处于加载状态中
  // children 是表格的实际内容
  return (
    <div className="art-loading-content-wrapper" style={{ filter: visible ? 'blur(1px)' : 'none' }}>
      {children}
    </div>
  )
}

function TableBody({ tbodyProps }) {
  // tbodyProps <tbody> 元素的 props
  return <tbody {...tbodyProps} />
}

function Row({ row, rowIndex, trProps }) {
  // row 该行数据
  // rowIndex 数据在 dataSource 中的下标
  // trProps <tr> 元素的 props
  return <tr {...trProps} />
}

function Cell({ row, rowIndex, column, colIndex, tdProps }) {
  // row 单元格的行数据
  // rowIndex 单元格的行下标
  // column 单元格的列配置
  // colIndex 单元格的列下标
  // tdProps <td> 元素的 props
  return <td {...tdProps} />
}
```

## column 对象结构

列配置注意事项：

- `name` 为必传字段
- 对于锁定的列（`lock=true`），宽度 `width` 为必传项
  - 推荐给所有的列都配置上宽度，或是给表格配置一个默认的列宽度

| 字段              | 类型                                                       |                                                                |
| ----------------- | ---------------------------------------------------------- | -------------------------------------------------------------- |
| `name`            | `string`                                                   | 列的名称                                                       |
| `code`            | `string`                                                   | 在数据中的字段 code                                            |
| `getValue`        | `(record: any, rowIndex: number) => any`                   | 自定义取数方法                                                 |
| `render`          | `(value: any, record: any, rowIndex: number) => ReactNode` | 自定义渲染方法                                                 |
| `getCellProps`    | `(value: any, record: any, rowIndex: number) => any`       | 自定义的获取单元格 props 的方法                                |
| `getSpanRect`     | `(value: any, record: any, rowIndex: number) => SpanRect`  | 在虚拟滚动的情况下设置单元格合并                               |
| `title`           | `ReactNode`                                                | 列标题的展示名称；在页面中进行展示时，该字段将覆盖 `name` 字段 |
| `width`           | `number`                                                   | 列的宽度，如果该列是锁定的，则宽度为必传项                     |
| `align`           | `'left' / 'center' / 'right'`                              | 单元格对齐方向                                                 |
| ~~`hidden`~~      | ~~`boolean`~~                                              | ~~是否隐藏~~                                                   |
| `lock`            | `boolean`                                                  | 是否锁列                                                       |
| `children`        | `ArtColumn[]`                                              | 该列的子节点                                                   |
| `headerCellProps` | `React.ThHTMLAttributes`                                   | 表头单元格的 props                                             |
| `features`        | `{ [key: string]: any }`                                   | 功能开关标记，用于对表格功能进行拓展                           |

## CSS 变量列表

`<BaseTable />` 中大部分样式都是通过 CSS variables 来定义的，你可以通过下面的方式对表格进行风格化：

```js
<BaseTable style={{ '--color': '#333', '--cell-border': 'none' }} />
```

目前组件支持的自定义 CSS 变量如下：

```typescript
export type BaseTableCSSVariables = Partial<{
  /** 表格一行的高度，注意该属性将被作为 CSS variable，不能使用数字作为简写 */
  '--row-height': string
  /** 表格的字体颜色 */
  '--color': string
  /** 表格背景颜色 */
  '--bgcolor': string
  /** 鼠标悬停时的背景色 */
  '--hover-bgcolor': string
  /** 单元格高亮时的背景色 */
  '--highlight-bgcolor': string

  /** 表头中一行的高度，注意该属性将被作为 CSS variable，不能使用数字作为简写 */
  '--header-row-height': string
  /** 表头中的字体颜色 */
  '--header-color': string
  /** 表头的背景色 */
  '--header-bgcolor': string
  /** 表头上鼠标悬停时的背景色 */
  '--header-hover-bgcolor': string
  /** 表头上单元格高亮时的背景色 */
  '--header-highlight-bgcolor': string

  /** 单元格 padding */
  '--cell-padding': string
  /** 字体大小 */
  '--font-size': string
  /** 表格内字体的行高 */
  '--line-height': string
  /** 锁列阴影，默认为 rgba(152, 152, 152, 0.5) 0 0 6px 2px */
  '--lock-shadow': string

  /** 单元格的边框颜色 */
  '--border-color': string
  /** 单元格边框，默认为 1px solid var(--border-color) */
  '--cell-border': string
  /** 单元格上下边框，默认为 var(--cell-border) */
  '--cell-border-horizontal': string
  /** 单元格左右边框，默认为 var(--cell-border) */
  '--cell-border-vertical': string
  /** 表头单元格边框，默认为 1px solid var(--border-color) */
  '--header-cell-border': string
  /** 表头单元格上下边框，默认为 var(--header-cell-border) */
  '--header-cell-border-horizontal': string
  /** 表头单元格左右边框，默认为 var(--header-cell-border) */
  '--header-cell-border-vertical': string
}>
```

当 CSS 变量无法满足自定义样式需求时，推荐通过 styled-components 来覆盖表格的默认样式。表格内各部分的 CSS 类名可以通过 `Classes` 对象来获取。

在更精细的场景下，可以使用 getCellProps 来定制每个单元格的样式。
